///////////////////////////////////////////////////////////////////////////
//
// Copyright (c) 2000-2003 Intel Corporation
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are met:
//
// * Redistributions of source code must retain the above copyright notice,
// this list of conditions and the following disclaimer.
// * Redistributions in binary form must reproduce the above copyright notice,
// this list of conditions and the following disclaimer in the documentation
// and/or other materials provided with the distribution.
// * Neither name of Intel Corporation nor the names of its contributors
// may be used to endorse or promote products derived from this software
// without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR
// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
// OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
///////////////////////////////////////////////////////////////////////////

#ifndef _TRINGLE_XML_H_
#define _TRINGLE_XML_H_

#include <stdio.h>
#include <string.h>
#include <malloc.h>
#include <assert.h>
//#include "tringle/xmltype.h"

#ifndef BOOL
typedef int BOOL;
#endif

#ifndef XmlChar
typedef char XmlChar ;
#endif

#define DOMString   char *


#ifndef TRUE
#define TRUE 1
#endif

#ifndef FALSE
#define FALSE 0
#endif

#ifndef IN
#define IN
#endif

#ifndef OUT
#define OUT
#endif

#ifndef INOUT
#define INOUT
#endif

/**@name DOM Interfaces
 * The Document Object Model consists of a set of objects and interfaces
 * for accessing and manipulating documents.  TRINGLE XML does not implement all
 * the interfaces documented in the DOM2-Core recommendation but defines
 * a subset of the most useful interfaces.  A description of the supported
 * interfaces and methods is presented in this section.
 *
 * For a complete discussion on the object model, the object hierarchy,
 * etc., refer to section 1.1 of the DOM2-Core recommendation.
 */

//@{

/*================================================================
*
*   DOM node type
*
*
*=================================================================*/
typedef enum
{
    E_INVALID_NODE                   = 0,
    E_ELEMENT_NODE                   = 1,
    E_ATTRIBUTE_NODE                 = 2,
    E_TEXT_NODE                      = 3,
    E_CDATA_SECTION_NODE             = 4,
    E_ENTITY_REFERENCE_NODE          = 5,
    E_ENTITY_NODE                    = 6,
    E_PROCESSING_INSTRUCTION_NODE    = 7,
    E_COMMENT_NODE                   = 8,
    E_DOCUMENT_NODE                  = 9,
    E_DOCUMENT_TYPE_NODE             = 10,
    E_DOCUMENT_FRAGMENT_NODE         = 11,
    E_NOTATION_NODE                  = 12,

}   XmlNodeType;

/*================================================================
*
*   error code
*
*
*=================================================================*/
typedef enum
{
    // see DOM spec
    XML_INDEX_SIZE_ERR                 = 1,
    XML_DOMSTRING_SIZE_ERR             = 2,
    XML_HIERARCHY_REQUEST_ERR          = 3,
    XML_WRONG_DOCUMENT_ERR             = 4,
    XML_INVALID_CHARACTER_ERR          = 5,
    XML_NO_DATA_ALLOWED_ERR            = 6,
    XML_NO_MODIFICATION_ALLOWED_ERR    = 7,
    XML_NOT_FOUND_ERR                  = 8,
    XML_NOT_SUPPORTED_ERR              = 9,
    XML_INUSE_ATTRIBUTE_ERR            = 10,
    XML_INVALID_STATE_ERR              = 11,
    XML_SYNTAX_ERR                     = 12,
    XML_INVALID_MODIFICATION_ERR       = 13,
    XML_NAMESPACE_ERR                  = 14,
    XML_INVALID_ACCESS_ERR             = 15,

    XML_OK                        = 0,
    XML_NO_SUCH_FILE                   = 101,
    XML_INSUFFICIENT_MEMORY            = 102,
    XML_FILE_DONE                      = 104,
    XML_INVALID_PARAMETER              = 105,
    XML_FAILED                         = 106,
    XML_INVALID_ITEM_NUMBER            = 107,

} XML_ERRORCODE;


#define DOCUMENTNODENAME    "#document"
#define TEXTNODENAME        "#text"
#define CDATANODENAME       "#cdata-section"

/*================================================================
*
*   DOM data structures
*
*
*=================================================================*/
typedef struct XmlDocument XmlDocument;

typedef struct XmlNode XmlNode;
struct XmlNode
{
    DOMString       nodeName;
    DOMString       nodeValue;
    XmlNodeType   nodeType;
    DOMString       namespaceURI;
    DOMString       prefix;
    DOMString       localName;
    BOOL            readOnly;

    XmlNode *         parentNode;
    XmlNode *         firstChild;
    XmlNode *         prevSibling;
    XmlNode *         nextSibling;
    XmlNode *         firstAttr;
    XmlDocument *     ownerDocument;

};

struct XmlDocument
{
    XmlNode    node;
};

typedef struct XmlCDATASection
{
    XmlNode    node;
} XmlCDATASection;

typedef struct XmlElement
{
    XmlNode   node;
    DOMString   tagName;
} XmlElement;

typedef struct XmlAttribute
{
    XmlNode   node;
    BOOL        specified;
    XmlElement *ownerElement;
} XmlAttribute;

typedef struct XmlText
{
    XmlNode   node;
} XmlText;

typedef struct XmlNodeList
{
    XmlNode    *nodeItem;
    struct  XmlNodeList *next;
} XmlNodeList;


typedef struct XmlNamedNodeMap
{
    XmlNode                 *nodeItem;
    struct XmlNamedNodeMap *next;
} XmlNamedNodeMap;

#ifdef __cplusplus
extern "C"
{
#endif

    /*================================================================
    *
    *   NODE interfaces
    *
    *
    *=================================================================*/

    /**@name Interface {\it Node}
     * The {\bf Node} interface forms the primary datatype for all other DOM
     * objects.  Every other interface is derived from this interface, inheriting
     * its functionality.  For more information, refer to DOM2-Core page 34.
     */

//@{

    /** Returns the name of the {\bf Node}, depending on what type of
     *  {\bf Node} it is, in a read-only string. Refer to the table in the
     *  DOM2-Core for a description of the node names for various interfaces.
     *
     *  @return [const DOMString] A constant {\bf DOMString} of the node name.
     */

    const DOMString
    XmlNodeGetNodeName(XmlNode *  nodeptr
                         /** Pointer to the node to retrieve the name. */
                        );

    /** Returns the value of the {\bf Node} as a string.  Note that this string
     *  is not a copy and modifying it will modify the value of the {\bf Node}.
     *
     *  @return [DOMString] A {\bf DOMString} of the {\bf Node} value.
     */

    DOMString
    XmlNodeGetNodeValue(XmlNode *  nodeptr
                          /** Pointer to the {\bf Node} to retrieve the value. */
                         );

    /** Assigns a new value to a {\bf Node}.  The {\bf newNodeValue} string is
     *  duplicated and stored in the {\bf Node} so that the original does not
     *  have to persist past this call.
     *
     *  @return [int] An integer representing one of the following:
     *    \begin{itemize}
     *      \item {\tt XML_OK}: The operation completed successfully.
     *      \item {\tt XML_INVALID_PARAMETER}: The {\bf Node*} is not a valid
     *            pointer.
     *      \item {\tt XML_INSUFFICIENT_MEMORY}: Not enough free memory exists
     *            to complete this operation.
     *    \end{itemize}
     */

    int
    XmlNodeSetNodeValue(XmlNode *  nodeptr,
                          /** The {\bf Node} to which to assign a new value. */
                          char *newNodeValue
                          /** The new value of the {\bf Node}. */
                         );

    /** Retrieves the type of a {\bf Node}.  The defined {\bf Node} constants
     *  are:
     *  \begin{itemize}
     *    \item {\tt E_ATTRIBUTE_NODE}
     *    \item {\tt E_CDATA_SECTION_NODE}
     *    \item {\tt E_COMMENT_NODE}
     *    \item {\tt E_DOCUMENT_FRAGMENT_NODE}
     *    \item {\tt E_DOCUMENT_NODE}
     *    \item {\tt E_DOCUMENT_TYPE_NODE}
     *    \item {\tt E_ELEMENT_NODE}
     *    \item {\tt E_ENTITY_NODE}
     *    \item {\tt E_ENTITY_REFERENCE_NODE}
     *    \item {\tt E_NOTATION_NODE}
     *    \item {\tt E_PROCESSING_INSTRUCTION_NODE}
     *    \item {\tt E_TEXT_NODE}
     *  \end{itemize}
     *
     *  @return [const unsigned short] An integer representing the type of the
     *          {\bf Node}.
     */

    const unsigned short
    XmlNodeGetNodeType(XmlNode *  nodeptr
                         /** The {\bf Node} from which to retrieve the type. */
                        );

    /** Retrieves the parent {\bf Node} for a {\bf Node}.
     *
     *  @return [Node*] A pointer to the parent {\bf Node} or {\tt NULL} if the
     *          {\bf Node} has no parent.
     */

    XmlNode*
    XmlNodeGetParentNode(XmlNode *  nodeptr
                           /** The {\bf Node} from which to retrieve the
                           parent. */
                          );

    /** Retrieves the list of children of a {\bf Node} in a {\bf NodeList}
     *  structure.  If a {\bf Node} has no children, {\bf XmlNodeGetChildNodes}
     *  returns a {\bf NodeList} structure that contains no {\bf Node}s.
     *
     *  @return [NodeList*] A {\bf NodeList} of the children of the {\bf Node}.
     */

    XmlNodeList*
    XmlNodeGetChildNodes(XmlNode *  nodeptr
                           /** The {\bf Node} from which to retrieve the
                           children. */
                          );

    /** Retrieves the first child {\bf Node} of a {\bf Node}.
     *
     *  @return [Node*] A pointer to the first child {\bf Node} or {\tt NULL}
     *                  if the {\bf Node} does not have any children.
     */

    XmlNode*
    XmlNodeGetFirstChild(XmlNode *  nodeptr
                           /** The {\bf Node} from which to retrieve the first
                           child.  */
                          );

    /** Retrieves the last child {\bf Node} of a {\bf Node}.
     *
     *  @return [Node*] A pointer to the last child {\bf Node} or {\tt NULL} if
     *                  the {\bf Node} does not have any children.
     */

    XmlNode*
    XmlNodeGetLastChild(XmlNode *  nodeptr
                          /** The {\bf Node} from which to retrieve the last
                          child. */
                         );

    /** Retrieves the sibling {\bf Node} immediately preceding this {\bf Node}.
     *
     *  @return [Node*] A pointer to the previous sibling {\bf Node} or
     *                  {\tt NULL} if no such {\bf Node} exists.
     */

    XmlNode*
    XmlNodeGetPreviousSibling(XmlNode *  nodeptr
                                /** The {\bf Node} for which to retrieve the
                                previous sibling.  */
                               );

    /** Retrieves the sibling {\bf Node} immediately following this {\bf Node}.
     *
     *  @return [Node*] A pointer to the next sibling {\bf Node} or {\tt NULL}
     *                  if no such {\bf Node} exists.
     */

    XmlNode*
    XmlNodeGetNextSibling(XmlNode *  nodeptr
                            /** The {\bf Node} from which to retrieve the next
                            sibling. */
                           );

    /** Retrieves the attributes of a {\bf Node}, if it is an {\bf Element} node,
     *  in a {\bf NamedNodeMap} structure.
     *
     *  @return [NamedNodeMap*] A {\bf NamedNodeMap} of the attributes or
     *                          {\tt NULL}.
     */

    XmlNamedNodeMap*
    XmlNodeGetAttributes(XmlNode *  nodeptr
                           /** The {\bf Node} from which to retrieve the
                           attributes. */
                          );

    /** Retrieves the document object associated with this {\bf Node}.  This
     *  owner document {\bf Node} allows other {\bf Node}s to be created in the
     *  context of this document.  Note that {\bf Document} nodes do not have
     *  an owner document.
     *
     *  @return [Document*] A pointer to the owning {\bf Document} or
     *                      {\tt NULL}, if the {\bf Node} does not have an owner.
     */

    XmlDocument*
    XmlNodeGetOwnerDocument(XmlNode *  nodeptr
                              /** The {\bf Node} from which to retrieve the
                              owner document. */
                             );

    /** Retrieves the namespace URI for a {\bf Node} as a {\bf DOMString}.  Only
     *  {\bf Node}s of type {\tt E_ELEMENT_NODE} or {\tt E_ATTRIBUTE_NODE} can
     *  have a namespace URI.  {\bf Node}s created through the {\bf Document}
     *  interface will only contain a namespace if created using
     *  {\bf XmlDocCreateElementNS}.
     *
     *  @return [const DOMString] A {\bf DOMString} representing the URI of the
     *                            namespace or {\tt NULL}.
     */

    const DOMString
    XmlNodeGetNamespaceURI(XmlNode *  nodeptr
                             /** The {\bf Node} for which to retrieve the
                             namespace. */
                            );

    /** Retrieves the namespace prefix, if present.  The prefix is the name
     *  used as an alias for the namespace URI for this element.  Only
     *  {\bf Node}s of type {\tt E_ELEMENT_NODE} or {\tt E_ATTRIBUTE_NODE} can have
     *  a prefix. {\bf Node}s created through the {\bf Document} interface will
     *  only contain a prefix if created using {\bf XmlDocCreateElementNS}.
     *
     *  @return [DOMString] A {\bf DOMString} representing the namespace prefix
     *                      or {\tt NULL}.
     */

    DOMString
    XmlNodeGetPrefix(XmlNode *  nodeptr
                       /** The {\bf Node} from which to retrieve the prefix. */
                      );

    /** Retrieves the local name of a {\bf Node}, if present.  The local name is
     *  the tag name without the namespace prefix.  Only {\bf Node}s of type
     *  {\tt E_ELEMENT_NODE} or {\tt E_ATTRIBUTE_NODE} can have a local name.
     *  {\Bf Node}s created through the {\bf Document} interface will only
     *  contain a local name if created using {\bf XmlDocCreateElementNS}.
     *
     *  @return [const DOMString] A {\bf DOMString} representing the local name
     *                            of the {\bf Element} or {\tt NULL}.
     */

    const DOMString
    XmlNodeGetLocalName(XmlNode *  nodeptr
                          /** The {\bf Node} from which to retrieve the local
                          name. */
                         );

    /** Inserts a new child {\bf Node} before the existing child {\bf Node}.
     *  {\bf refChild} can be {\tt NULL}, which inserts {\bf newChild} at the
     *  end of the list of children.  Note that the {\bf Node} (or {\bf Node}s)
     *  in {\bf newChild} must already be owned by the owner document (or have no
     *  owner at all) of {\bf nodeptr} for insertion.  If not, the {\bf Node}
     *  (or {\bf Node}s) must be imported into the document using
     *  {\bf XmlDocImportNode}.  If {\bf newChild} is already in the tree,
     *  it is removed first.
     *
     *  @return [int] An integer representing one of the following:
     *    \begin{itemize}
     *      \item {\tt XML_OK}: The operation completed successfully.
     *      \item {\tt XML_INVALID_PARAMETER}: Either {\bf nodeptr} or
     *            {\bf newChild} is {\tt NULL}.
     *      \item {\tt XML_HIERARCHY_REQUEST_ERR}: The type of the {\bf Node}
     *            does not allow children of the type of {\bf newChild}.
     *      \item {\tt XML_WRONG_DOCUMENT_ERR}: {\bf newChild} has an owner
     *            document that does not match the owner of {\bf nodeptr}.
     *      \item {\tt XML_NO_MODIFICATION_ALLOWED_ERR}: {\bf nodeptr} is
     *            read-only or the parent of the {\bf Node} being inserted is
     *            read-only.
     *      \item {\tt XML_NOT_FOUND_ERR}: {\bf refChild} is not a child of
     *            {\bf nodeptr}.
     *    \end{itemize}
     */

    int
    XmlNodeInsertBefore(XmlNode *  nodeptr,
                          /** The parent of the {\bf Node} before which to
                          insert the new child. */
                          XmlNode* newChild,
                          /** The {\bf Node} to insert into the tree. */
                          XmlNode* refChild
                          /** The reference child where the new {\bf Node}
                          should be inserted. The new {\bf Node} will
                          appear directly before the reference child. */
                         );

    /** Replaces an existing child {\bf Node} with a new child {\bf Node} in
     *  the list of children of a {\bf Node}. If {\bf newChild} is already in
     *  the tree, it will first be removed. {\bf returnNode} will contain the
     *  {\bf oldChild} {\bf Node}, appropriately removed from the tree (i.e. it
     *  will no longer have an owner document).
     *
     *  @return [int] An integer representing one of the following:
     *    \begin{itemize}
     *      \item {\tt XML_OK}: The operation completed successfully.
     *      \item {\tt XML_INVALID_PARAMTER: Either {\bf nodeptr}, {\bf
     *            newChild}, or {\bf oldChild} is {\tt NULL}.
     *      \item {\tt XML_HIERARCHY_REQUEST_ERR}: The {\bf newChild} is not
     *            a type of {\bf Node} that can be inserted into this tree or
     *            {\bf newChild} is an ancestor of {\bf nodePtr}.
     *      \item {\tt XML_WRONG_DOCUMENT_ERR}: {\bf newChild} was created from
     *            a different document than {\bf nodeptr}.
     *      \item {\tt XML_NO_MODIFICATION_ALLOWED_ERR}: {\bf nodeptr} or
     *            its parent is read-only.
     *      \item {\tt XML_NOT_FOUND_ERR}: {\bf oldChild} is not a child of
     *            {\bf nodeptr}.
     *    \end{itemize}
     */

    int
    XmlNodeReplaceChild(XmlNode *  nodeptr,
                          /** The parent of the {\bf Node} which contains the
                          child to replace. */
                          XmlNode* newChild,
                          /** The child with which to replace {\bf oldChild}. */
                          XmlNode* oldChild,
                          /** The child to replace with {\bf newChild}. */
                          XmlNode** returnNode
                          /** Pointer to a {\bf Node} to place the removed {\bf
                          oldChild} {\bf Node}. */
                         );

    /** Removes a child from the list of children of a {\bf Node}.
     *  {\bf returnNode} will contain the {\bf oldChild} {\bf Node},
     *  appropriately removed from the tree (i.e. it will no longer have an
     *  owner document).
     *
     *  @return [int] An integer representing one of the following:
     *    \begin{itemize}
     *      \item {\tt XML_OK}: The operation completed successfully.
     *      \item {\tt XML_INVALID_PARAMETER}: Either {\bf nodeptr} or
     *            {\bf oldChild} is {\tt NULL}.
     *      \item {\tt XML_NO_MODIFICATION_ALLOWED_ERR}: {\bf nodeptr} or its
     *            parent is read-only.
     *      \item {\tt XML_NOT_FOUND_ERR}: {\bf oldChild} is not among the
     *            children of {\bf nodeptr}.
     *    \end{itemize}
     */

    int
    XmlNodeRemoveChild(XmlNode *  nodeptr,
                         /** The parent of the child to remove. */
                         XmlNode* oldChild,
                         /** The child {\bf Node} to remove. */
                         XmlNode **returnNode
                         /** Pointer to a {\bf Node} to place the removed {\bf
                         oldChild} {\bf Node}. */
                        );

    /** Appends a child {\bf Node} to the list of children of a {\bf Node}.  If
     *  {\bf newChild} is already in the tree, it is removed first.
     *
     *  @return [int] An integer representing one of the following:
     *    \begin{itemize}
     *      \item {\tt XML_OK}: The operation completed successfully.
     *      \item {\tt XML_INVALID_PARAMETER}: Either {\bf nodeptr} or
     *            {\bf newChild} is {\tt NULL}.
     *      \item {\tt XML_HIERARCHY_REQUEST_ERR}: {\bf newChild} is of a type
     *            that cannot be added as a child of {\bf nodeptr} or
     *            {\bf newChild} is an ancestor of {\bf nodeptr}.
     *      \item {\tt XML_WRONG_DOCUMENT_ERR}: {\bf newChild} was created from
     *            a different document than {\bf nodeptr}.
     *      \item {\tt XML_NO_MODIFICATION_ALLOWED_ERR}: {\bf nodeptr} is a
     *            read-only {\bf Node}.
     */

    int
    XmlNodeAppendChild(XmlNode *  nodeptr,
                         /** The {\bf Node} in which to append the new child. */
                         XmlNode* newChild
                         /** The new child to append. */
                        );

    /** Queries whether or not a {\bf Node} has children.
     *
     *  @return [BOOL] {\tt TRUE} if the {\bf Node} has one or more children
     *                 otherwise {\tt FALSE}.
     */

    BOOL
    XmlNodeHasChildNodes(XmlNode *  nodeptr
                           /** The {\bf Node} to query for children. */
                          );

    /** Clones a {\bf Node}.  The new {\bf Node} does not have a parent.  The
     *  {\bf deep} parameter controls whether the subtree of the {\bf Node} is
     *  also cloned.  For details on cloning specific types of {\bf Node}s,
     *  refer to the DOM2-Core recommendation.
     *
     *  @return [Node*] A clone of {\bf nodeptr} or {\tt NULL}.
     */

    XmlNode*
    XmlNodeCloneNode(XmlNode *  nodeptr,
                       /** The {\bf Node} to clone.  */
                       BOOL deep
                       /** {\tt TRUE} to clone the subtree also or {\tt FALSE}
                           to clone only {\bf nodeptr}. */
                      );

    /** Queries whether this {\bf Node} has attributes.  Note that only
     *  {\bf Element} nodes have attributes.
     *
     *  @return [BOOL] {\tt TRUE} if the {\bf Node} has attributes otherwise
     *                 {\tt FALSE}.
     */

    BOOL
    XmlNodeHasAttributes(XmlNode *  node
                           /** The {\bf Node} to query for attributes. */
                          );

    /** Frees a {\bf Node} and all {\bf Node}s in its subtree.
     *
     *  @return [void] This function does not return a value.
     */

    void
    XmlNodeFree(XmlNode *  XmlNode
                  /** The {\bf Node} to free. */
                 );

//@}

    /*================================================================
    *
    *   Attribute interfaces
    *
    *
    *=================================================================*/

    /**@name Interface {\it Attr}
     * The {\bf Attr} interface represents an attribute of an {\bf Element}.
     * The document type definition (DTD) or schema usually dictate the
     * allowable attributes and values for a particular element.  For more
     * information, refer to the {\it Interface Attr} section in the DOM2-Core.
     */
//@{


    /** Frees an {\bf Attr} node.
     *
     *  @return [void] This function does not return a value.
     */

    void
    XmlAttrFree(IN XmlAttribute *attrNode
                  /** The {\bf Attr} node to free.  */
                 );

//@}


    /*================================================================
    *
    *   CDATASection interfaces
    *
    *
    *=================================================================*/

    /**@name Interface {\it CDATASection}
     * The {\bf CDATASection} is used to escape blocks of text containing
     * characters that would otherwise be regarded as markup. CDATA sections
     * cannot be nested. Their primary purpose is for including material such
     * XML fragments, without needing to escape all the delimiters.  For more
     * information, refer to the {\it Interface CDATASection} section in the
     * DOM2-Core.
     */
//@{


    /** Initializes a {\bf CDATASection} node.
     *
     *  @return [void] This function does not return a value.
     */

    void
    XmlCDATASectionInit(XmlCDATASection *nodeptr
                          /** The {\bf CDATASection} node to initialize.  */
                         );


    /** Frees a {\bf CDATASection} node.
     *
     *  @return [void] This function does not return a value.
     */

    void
    XmlCDATASectionFree(XmlCDATASection *nodeptr
                          /** The {\bf CDATASection} node to free. */
                         );

//@}

    /*================================================================
    *
    *   Document interfaces
    *
    *
    *=================================================================*/

    /**@name Interface {\it Document}
     * The {\bf Document} interface represents the entire XML document.
     * In essence, it is the root of the document tree and provides the
     * primary interface to the elements of the document.  For more information,
     * refer to the {\it Interface Document} section in the DOM2Core.
     */
//@{

    /** Initializes a {\bf Document} node.
     *
     *  @return [void] This function does not return a value.
     */

    void
    XmlDocumentInit(XmlDocument *nodeptr
                      /** The {\bf Document} node to initialize.  */
                     );

    /** Creates a new empty {\bf Document} node.  The
     *  {\bf XmlDocCreateDocumentEx} API differs from the {\bf
     *  XmlDocCreateDocument} API in that it returns an error code
     *  describing the reason for the failure rather than just {\tt NULL}.
     *
     *  @return [int] An integer representing one of the following:
     *    \begin{itemize}
     *      \item {\tt XML_OK}: The operation completed successfully.
     *      \item {\tt XML_INSUFFICIENT_MEMORY}: Not enough free memory exists
     *            to complete this operation.
     *    \end{itemize}
     */

    int XmlDocCreateDocumentEx(XmlDocument** doc
                                      /** Pointer to a {\bf Document} where the
                                      new object will be stored. */
                                     );


    /** Creates a new empty {\bf Document} node.
     *
     *  @return [Document*] A pointer to the new {\bf Document} or {\tt NULL} on
     *                      failure.
     */

    XmlDocument* XmlDocCreateDocument();

    /** Creates a new {\bf Element} node with the given tag name.  The new
     *  {\bf Element} node has a {\tt nodeName} of {\bf tagName} and
     *  the {\tt localName}, {\tt prefix}, and {\tt namespaceURI} set
     *  to {\tt NULL}.  To create an {\bf Element} with a namespace,
     *  see {\bf XmlDocCreateElementNS}.
     *
     *  The {\bf XmlDocCreateElementEx} API differs from the {\bf
     *  XmlDocCreateElement} API in that it returns an error code
     *  describing the reason for failure rather than just {\tt NULL}.
     *
     *  @return [int] An integer representing one of the following:
     *    \begin{itemize}
     *      \item {\tt XML_OK}: The operation completed successfully.
     *      \item {\tt XML_INVALID_PARAMETER}: Either {\bf doc} or
     *            {\bf tagName} is {\tt NULL}.
     *      \item {\tt XML_INSUFFICIENT_MEMORY}: Not enough free memory exists
     *            to complete this operation.
     *    \end{itemize}
     */

    int
    XmlDocCreateElementEx(XmlDocument *doc,
                                 /** The owner {\bf Document} of the new node. */
                                 DOMString tagName,
                                 /** The tag name of the new {\bf Element}
                                 node. */
                                 XmlElement **rtElement
                                 /** Pointer to an {\bf Element} where the new
                                 object will be stored. */
                                );

    /** Creates a new {\bf Element} node with the given tag name.  The new
     *  {\bf Element} node has a {\tt nodeName} of {\bf tagName} and
     *  the {\tt localName}, {\tt prefix}, and {\tt namespaceURI} set
     *  to {\tt NULL}.  To create an {\bf Element} with a namespace,
     *  see {\bf XmlDocCreateElementNS}.
     *
     *  @return [Document*] A pointer to the new {\bf Element} or {\tt NULL} on
     *                      failure.
     */

    XmlElement*
    XmlDocCreateElement(XmlDocument *doc,
                               /** The owner {\bf Document} of the new node. */
                               DOMString tagName
                               /** The tag name of the new {\bf Element} node. */
                              );


    /** Creates a new {\bf Text} node with the given data.
     *  The {\bf XmlDocCreateTextNodeEx} API differs from the {\bf
     *  XmlDocCreateTextNode} API in that it returns an error code
     *  describing the reason for failure rather than just {\tt NULL}.
     *
     *  @return [int] An integer representing one of the following:
     *    \begin{itemize}
     *      \item {\tt XML_OK}: The operation completed successfully.
     *      \item {\tt XML_INVALID_PARAMETER}: Either {\bf doc} or {\bf data}
     *            is {\tt NULL}.
     *      \item {\tt XML_INSUFFICIENT_MEMORY}: Not enough free memory exists
     *            to complete this operation.
     *    \end{itemize}
     */

    int
    XmlDocCreateTextNodeEx(XmlDocument *doc,
                                  /** The owner {\bf Document} of the new node. */
                                  DOMString data,
                                  /** The data to associate with the new {\bf
                                  Text} node. */
                                  XmlNode** textNode
                                  /** A pointer to a {\bf Node} where the new
                                  object will be stored. */
                                 );


    /** Creates a new {\bf Text} node with the given data.
     *
     *  @return [Node*] A pointer to the new {\bf Node} or {\tt NULL} on failure.
     */

    XmlNode*
    XmlDocCreateTextNode(XmlDocument *doc,
                                /** The owner {\bf Document} of the new node. */
                                DOMString data
                                /** The data to associate with the new {\bf Text}
                                    node. */
                               );

    /** Creates a new {\bf CDATASection} node with given data.
     *
     *  The {\bf XmlDocCreateCDATASectionEx} API differs from the {\bf
     *  XmlDocCreateCDATASection} API in that it returns an error code
     *  describing the reason for failure rather than just {\tt NULL}.
     *
     *  @return [int] An integer representing one of the following:
     *    \begin{itemize}
     *      \item {\tt XML_OK}: The operation completed successfully.
     *      \item {\tt XML_INVALID_PARAMETER}: Either {\bf doc} or {\bd data}
     *            is {\tt NULL}.
     *      \item {\tt XML_INSUFFICIENT_MEMORY}: Not enough free memory exists
     *            to complete this operation.
     *    \end{itemize}
     */

    int
    XmlDocCreateCDATASectionEx(XmlDocument *doc,
                                      /** The owner {\bf Document} of the new
                                      node. */
                                      DOMString data,
                                      /** The data to associate with the new
                                          {\bf CDATASection} node. */
                                      XmlCDATASection** cdNode
                                      /** A pointer to a {\bf Node} where the
                                          new object will be stored. */
                                     );


    /** Creates a new {\bf CDATASection} node with given data.
     *
     *  @return [CDATASection*] A pointer to the new {\bf CDATASection} or
     *                          {\tt NULL} on failure.
     */

    XmlCDATASection*
    XmlDocCreateCDATASection(XmlDocument *doc,
                                    /** The owner {\bf Document} of the new
                                        node. */
                                    DOMString data
                                    /** The data to associate with the new {\bf
                                        CDATASection} node. */
                                   );

    /** Creates a new {\bf Attr} node with the given name.
     *
     *  @return [Attr*] A pointer to the new {\bf Attr} or {\tt NULL} on failure.
     */

    XmlAttribute*
    XmlDocCreateAttribute(XmlDocument *doc,
                                 /** The owner {\bf Document} of the new node. */
                                 char *name
                                 /** The name of the new attribute. */
                                );


    /** Creates a new {\bf Attr} node with the given name.
     *
     *  The {\bf XmlDocCreateAttributeEx} API differs from the {\bf
     *  XmlDocCreateAttribute} API in that it returns an error code
     *  describing the reason for failure rather than just {\tt NULL}.
     *
     *  @return [int] An integer representing one of the following:
     *    \begin{itemize}
     *      \item {\tt XML_OK}: The operation completed successfully.
     *      \item {\tt XML_INVALID_PARAMETER}: Either {\bf doc} or {\bf name}
     *            is {\tt NULL}.
     *      \item {\tt XML_INSUFFICIENT_MEMORY}: Not enough free memory exists
     *            to complete this operation.
     *    \end{itemize}
     */

    int
    XmlDocCreateAttributeEx(XmlDocument *doc,
                                   /** The owner {\bf Document} of the new
                                   node. */
                                   char *name,
                                   /** The name of the new attribute. */
                                   XmlAttribute** attrNode
                                   /** A pointer to a {\bf Attr} where the new
                                   object will be stored. */
                                  );


    /** Returns a {\bf NodeList} of all {\bf Elements} that match the given
     *  tag name in the order in which they were encountered in a preorder
     *  traversal of the {\bf Document} tree.
     *
     *  @return [NodeList*] A pointer to a {\bf NodeList} containing the
     *                      matching items or {\tt NULL} on an error.
     */

    XmlNodeList*
    XmlDocGetElementsByTagName(XmlDocument *doc,
                                      /** The {\bf Document} to search. */
                                      DOMString tagName
                                      /** The tag name to find. */
                                     );

// introduced in DOM level 2

    /** Creates a new {\bf Element} node in the given qualified name and
     *  namespace URI.
     *
     *  The {\bf XmlDocCreateElementNSEx} API differs from the {\bf
     *  XmlDocCreateElementNS} API in that it returns an error code
     *  describing the reason for failure rather than just {\tt NULL}.
     *
     *  @return [int] An integer representing one of the following:
     *    \begin{itemize}
     *      \item {\tt XML_OK}: The operation completed successfully.
     *      \item {\tt XML_INVALID_PARAMETER}: Either {\bf doc},
     *            {\bf namespaceURI}, or {\bf qualifiedName} is {\tt NULL}.
     *      \item {\tt XML_INSUFFICIENT_MEMORY}: Not enough free memory exists
     *            to complete this operation.
     *    \end{itemize}
     */

    int
    XmlDocCreateElementNSEx(XmlDocument *doc,
                                   /** The owner {\bf Document} of the new
                                   node. */
                                   DOMString namespaceURI,
                                   /** The namespace URI for the new {\bf
                                   Element}. */
                                   DOMString qualifiedName,
                                   /** The qualified name of the new {\bf
                                   Element}. */
                                   XmlElement** rtElement
                                   /** A pointer to an {\bf Element} where the
                                   new object will be stored. */
                                  );


    /** Creates a new {\bf Element} node in the given qualified name and
     *  namespace URI.
     *
     *  @return [Element*] A pointer to the new {\bf Element} or {\tt NULL} on
     *                     failure.
     */

    XmlElement*
    XmlDocCreateElementNS(XmlDocument *doc,
                                 /** The owner {\bf Document} of the new node. */
                                 DOMString namespaceURI,
                                 /** The namespace URI for the new {\bf
                                 Element}. */
                                 DOMString qualifiedName
                                 /** The qualified name of the new {\bf
                                 Element}. */
                                );

    /** Creates a new {\bf Attr} node with the given qualified name and
     *  namespace URI.
     *
     *  The {\bf XmlDocCreateAttributeNSEx} API differs from the {\bf
     *  XmlDocCreateAttributeNS} API in that it returns an error code
     *  describing the reason for failure rather than just {\tt NULL}.
     *
     *  @return [int] An integer representing one of the following:
     *    \begin{itemize}
     *      \item {\tt XML_OK}: The operation completed successfully.
     *      \item {\tt XML_INVALID_PARAMETER}: Either {\bf doc},
     *            {\bf namespaceURI}, or {\bf qualifiedName} is {\tt NULL}.
     *      \item {\tt XML_INSUFFICIENT_MEMORY}: Not enough free memory exists
     *            to complete this operation.
     *    \end{itemize}
     */

    int
    XmlDocCreateAttributeNSEx(XmlDocument *doc,
                                     /** The owner {\bf Document} of the new
                                     {\bf Attr}. */
                                     DOMString namespaceURI,
                                     /** The namespace URI for the attribute. */
                                     DOMString qualifiedName,
                                     /** The qualified name of the attribute. */
                                     XmlAttribute** attrNode
                                     /** A pointer to an {\bf Attr} where the
                                         new object will be stored. */
                                    );

    /** Creates a new {\bf Attr} node with the given qualified name and
     *  namespace URI.
     *
     *  @return [Attr*] A pointer to the new {\bf Attr} or {\tt NULL} on failure.
     */

    XmlAttribute*
    XmlDocCreateAttributeNS(XmlDocument *doc,
                                   /** The owner {\bf Document} of the new
                                   {\bf Attr}. */
                                   DOMString namespaceURI,
                                   /** The namespace URI for the attribute. */
                                   DOMString qualifiedName
                                   /** The qualified name of the attribute. */
                                  );

    /** Returns a {\bf NodeList} of {\bf Elements} that match the given
     *  local name and namespace URI in the order they are encountered
     *  in a preorder traversal of the {\bf Document} tree.  Either
     *  {\bf namespaceURI} or {\bf localName} can be the special {\tt "*"}
     *  character, which matches any namespace or any local name respectively.
     *
     *  @return [NodeList*] A pointer to a {\bf NodeList} containing the
     *                      matching items or {\tt NULL} on an error.
     */

    XmlNodeList*
    XmlDocGetElementsByTagNameNS(XmlDocument* doc,
                                        /** The {\bf Document} to search. */
                                        DOMString namespaceURI,
                                        /** The namespace of the elements to
                                                            find or {\tt "*"} to match any
                                                            namespace. */
                                        DOMString localName
                                        /** The local name of the elements to
                                                            find or {\tt "*"} to match any local
                                                            name.  */
                                       );

    /** Returns the {\bf Element} whose {\tt ID} matches that given id.
     *
     *  @return [Element*] A pointer to the matching {\bf Element} or
     *                     {\tt NULL} on an error.
     */

    XmlElement*
    XmlDocGetElementById(XmlDocument* doc,
                                /** The owner {\bf Document} of the {\bf
                                Element}. */
                                DOMString tagName
                                /** The name of the {\bf Element}.*/
                               );

    /** Frees a {\bf Document} object and all {\bf Node}s associated with it.
     *  Any {\bf Node}s extracted via any other interface function, e.g.
     *  {\bf XmlDocument_GetElementById}, become invalid after this call unless
     *  explicitly cloned.
     *
     *  @return [void] This function does not return a value.
     */

    void
    XmlDocumentFree(XmlDocument* doc
                      /** The {\bf Document} to free.  */
                     );

    /** Imports a {\bf Node} from another {\bf Document} into this
     *  {\bf Document}.  The new {\bf Node} does not a have parent node: it is a
     *  clone of the original {\bf Node} with the {\tt ownerDocument} set to
     *  {\bf doc}.  The {\bf deep} parameter controls whether all the children
     *  of the {\bf Node} are imported.  Refer to the DOM2-Core recommendation
     *  for details on importing specific node types.
     *
     *  @return [int] An integer representing one of the following:
     *    \begin{itemize}
     *      \item {\tt XML_OK}: The operation completed successfully.
     *      \item {\tt XML_INVALID_PARAMETER}: Either {\bf doc} or
     *            {\bf importNode} is not a valid pointer.
     *      \item {\tt XML_NOT_SUPPORTED_ERR}: {\bf importNode} is a
     *            {\bf Document}, which cannot be imported.
     *      \item {\tt XML_FAILED}: The import operation failed because the
     *            {\bf Node} to be imported could not be cloned.
     *    \end{itemize}
     */

    int
    XmlDocImportNode(XmlDocument* doc,
                            /** The {\bf Document} into which to import. */
                            XmlNode* importNode,
                            /** The {\bf Node} to import. */
                            BOOL deep,
                            /** {\tt TRUE} to import all children of {\bf
                                importNode} or {\tt FALSE} to import only the
                                root node. */
                            XmlNode** rtNode
                            /** A pointer to a new {\bf Node} owned by {\bf
                                doc}. */
                           );
//@}

    /*================================================================
    *
    *   Element interfaces
    *
    *
    *=================================================================*/

    /**@name Interface {\it Element}
     * The {\bf Element} interface represents an element in an XML document.
     * Only {\bf Element}s are allowed to have attributes, which are stored in the
     * {\tt attributes} member of a {\bf Node}.  The {\bf Element} interface
     * extends the {\bf Node} interface and adds more operations to manipulate
     * attributes.
     */
//@{

    /** Initializes a {\bf XmlElement} node.
     *
     *  @return [void] This function does not return a value.
     */

    void XmlElementInit(XmlElement *element
                          /** The {\bf Element} to initialize.*/
                         );


    /** Returns the name of the tag as a constant string.
     *
     *  @return [const DOMString] A {\bf DOMString} representing the name of the
     *                            {\bf Element}.
     */

    const DOMString
    XmlElementGetTagName(XmlElement* element
                           /** The {\bf Element} from which to retrieve the
                           name. */
                          );

    /** Retrieves an attribute of an {\bf Element} by name.
     *
     *  @return [DOMString] A {\bf DOMString} representing the value of the
     *                      attribute.
     */

    DOMString
    XmlElementGetAttribute(XmlElement* element,
                             /** The {\bf Element} from which to retrieve the
                             attribute. */
                             DOMString name
                             /** The name of the attribute to retrieve. */
                            );

    /** Adds a new attribute to an {\bf Element}.  If an attribute with the same
     *  name already exists, the attribute value will be updated with the
     *  new value in {\bf value}.
     *
     *  @return [int] An integer representing of the following:
     *    \begin{itemize}
     *      \item {\tt XML_OK}: The operation completed successfully.
     *      \item {\tt XML_INVALID_PARAMETER}: Either {\bf element},
     *            {\bf name}, or {\bf value} is {\tt NULL}.
     *      \item {\tt XML_INVALID_CHARACTER_ERR}: {\bf name} contains an
     *            illegal character.
     *      \item {\tt XML_INSUFFICIENT_MEMORY}: Not enough free memory exists
     *            to complete the operation.
     *    \end{itemize}
     */

    int
    XmlElementSetAttribute(XmlElement* element,
                             /** The {\bf Element} on which to set the
                             attribute. */
                             DOMString name,
                             /** The name of the attribute. */
                             DOMString value
                             /** The value of the attribute.  Note that this is
                                 a non-parsed string and any markup must be
                                 escaped. */
                            );

    /** Removes an attribute by name.
     *
     *  @return [int] An integer representing one of the following:
     *    \begin{itemize}
     *      \item {\tt XML_OK}: The operation completed successfully.
     *      \item {\tt XML_INVALID_PARAMETER}: Either {\bf element} or
     *            {\bf name} is {\tt NULL}.
     *    \end{itemize}
     */

    int
    XmlElementRemoveAttribute(XmlElement* element,
                                /** The {\bf Element} from which to remove the
                                attribute. */
                                DOMString name
                                /** The name of the attribute to remove.  */
                               );

    /** Retrieves an attribute node by name.  See
     *  {\bf XmlElementGetAttributeNodeNS} to retrieve an attribute node using
     *  a qualified name or namespace URI.
     *
     *  @return [Attr*] A pointer to the attribute matching {\bf name} or
     *                  {\tt NULL} on an error.
     */

    XmlAttribute*
    XmlElementGetAttributeNode(XmlElement* element,
                                 /** The {\bf Element} from which to get the
                                 attribute node.  */
                                 DOMString name
                                 /** The name of the attribute node to find. */
                                );

    /** Adds a new attribute node to an {\bf Element}.  If an attribute already
     *  exists with {\bf newAttr} as a name, it will be replaced with the
     *  new one and the old one will be returned in {\bf rtAttr}.
     *
     *  @return [int] An integer representing one of the following:
     *    \begin{itemize}
     *      \item {\tt XML_OK}: The operation completed successfully.
     *      \item {\tt XML_INVALID_PARAMETER}: Either {\bf element} or
     *            {\bf newAttr} is {\tt NULL}.
     *      \item {\tt XML_WRONG_DOCUMENT_ERR}: {\bf newAttr} does not belong
     *            to the same one as {\bf element}.
     *      \item {\tt XML_INUSE_ATTRIBUTE_ERR}: {\bf newAttr} is already
     *            an attribute of another {\bf Element}.
     *    \end{itemize}
     */

    int
    XmlElementSetAttributeNode(XmlElement* element,
                                 /** The {\bf Element} in which to add the new
                                 attribute. */
                                 XmlAttribute* newAttr,
                                 /** The new {\bf Attr} to add. */
                                 XmlAttribute** rtAttr
                                 /** A pointer to an {\bf Attr} where the old
                                 {\bf Attr} will be stored.  This will have
                                 a {\tt NULL} if no prior node
                                 existed. */
                                );

    /** Removes the specified attribute node from an {\bf Element}.
     *
     *  @return [int] An integer representing one of the following:
     *    \begin{itemize}
     *      \item {\tt XML_OK}: The operation completed successfully.
     *      \item {\tt XML_INVALID_PARAMETER}: Either {\bf element} or
     *            {\bf oldAttr} is {\tt NULL}.
     *      \item {\tt XML_NOT_FOUND_ERR}: {\bf oldAttr} is not among the list
     *            attributes of {\bf element}.
     *    \end{itemize}
     */

    int
    XmlElementRemoveAttributeNode(XmlElement* element,
                                    /** The {\bf Element} from which to remove
                                    the attribute. */
                                    XmlAttribute* oldAttr,
                                    /** The attribute to remove from the {\bf
                                        Element}. */
                                    XmlAttribute** rtAttr
                                    /** A pointer to an attribute in which to
                                        place the removed attribute. */
                                   );

    /** Returns a {\bf NodeList} of all {\it descendant} {\bf Elements} with
     *  a given tag name, in the order in which they are encountered in a
     *  pre-order traversal of this {\bf Element} tree.
     *
     *  @return [NodeList*] A {\bf NodeList} of the matching {\bf Element}s or
     *                      {\tt NULL} on an error.
     */

    XmlNodeList*
    XmlElementGetElementsByTagName(XmlElement* element,
                                     /** The {\bf Element} from which to start
                                     the search. */
                                     DOMString tagName
                                     /** The name of the tag for which to
                                         search. */
                                    );

// introduced in DOM 2

    /** Retrieves an attribute value using the local name and namespace URI.
     *
     *  @return [DOMString] A {\bf DOMString} representing the value of the
     *                      matching attribute.
     */

    DOMString
    XmlElementGetAttributeNS(XmlElement* element,
                               /** The {\bf Element} from which to get the
                               attribute value. */
                               DOMString namespaceURI,
                               /** The namespace URI of the attribute. */
                               DOMString localname
                               /** The local name of the attribute. */
                              );

    /** Adds a new attribute to an {\bf Element} using the local name and
     *  namespace URI.  If another attribute matches the same local name and
     *  namespace, the prefix is changed to be the prefix part of the
     *  {\tt qualifiedName} and the value is changed to {\bf value}.
     *
     *  @return [int] An integer representing one of the following:
     *    \begin{itemize}
     *      \item {\tt XML_OK}: The operation completed successfully.
     *      \item {\tt XML_INVALID_PARAMETER}: Either {\bf element},
     *            {\bf namespaceURI}, {\bf qualifiedName}, or {\bf value} is
     *            {\tt NULL}.
     *      \item {\tt XML_INVALID_CHARACTER_ERR}: {\bf qualifiedName} contains
     *            an invalid character.
     *      \item {\tt XML_NAMESPACE_ERR}: Either the {\bf qualifiedName} or
     *            {\bf namespaceURI} is malformed.  Refer to the DOM2-Core for
     *            possible reasons.
     *      \item {\tt XML_INSUFFICIENT_MEMORY}: Not enough free memory exist
     *            to complete the operation.
     *      \item {\tt XML_FAILED}: The operation could not be completed.
     *    \end{itemize}
     */

    int
    XmlElementSetAttributeNS(XmlElement* element,
                               /** The {\bf Element} on which to set the
                               attribute. */
                               DOMString namespaceURI,
                               /** The namespace URI of the new attribute. */
                               DOMString qualifiedName,
                               /** The qualified name of the attribute. */
                               DOMString value
                               /** The new value for the attribute. */
                              );

    /** Removes an attribute using the namespace URI and local name.
     *
     *  @return [int] An integer representing one of the following:
     *    \begin{itemize}
     *      \item {\tt XML_OK}: The operation completed successfully.
     *      \item {\tt XML_INVALID_PARAMETER}: Either {\bf element},
     *            {\bf namespaceURI}, or {\bf localName} is {\tt NULL}.
     *    \end{itemize}
     */

    int
    XmlElementRemoveAttributeNS(XmlElement* element,
                                  /** The {\bf Element} from which to remove the
                                  the attribute. */
                                  DOMString namespaceURI,
                                  /** The namespace URI of the attribute. */
                                  DOMString localName
                                  /** The local name of the attribute.*/
                                 );

    /** Retrieves an {\bf Attr} node by local name and namespace URI.
     *
     *  @return [Attr*] A pointer to an {\bf Attr} or {\tt NULL} on an error.
     */

    XmlAttribute*
    XmlElementGetAttributeNodeNS(XmlElement* element,
                                   /** The {\bf Element} from which to get the
                                   attribute. */
                                   DOMString namespaceURI,
                                   /** The namespace URI of the attribute. */
                                   DOMString localName
                                   /** The local name of the attribute. */
                                  );

    /** Adds a new attribute node.  If an attribute with the same local name
     *  and namespace URI already exists in the {\bf Element}, the existing
     *  attribute node is replaced with {\bf newAttr} and the old returned in
     *  {\bf rcAttr}.
     *
     *  @return [int] An integer representing one of the following:
     *    \begin{itemize}
     *      \item {\tt XML_OK}: The operation completed successfully.
     *      \item {\tt XML_INVALID_PARAMETER}: Either {\bf element} or
     *            {\bf newAttr} is {\tt NULL}.
     *      \item {\tt XML_WRONG_DOCUMENT_ERR}: {\bf newAttr} does not belong
     *            to the same document as {\bf element}.
     *      \item {\tt XML_INUSE_ATTRIBUTE_ERR}: {\bf newAttr} already is an
     *            attribute of another {\bf Element}.
     *    \end{itemize}
     */

    int
    XmlElementSetAttributeNodeNS(XmlElement* element,
                                   /** The {\bf Element} in which to add the
                                   attribute node. */
                                   XmlAttribute*   newAttr,
                                   /** The new {\bf Attr} to add. */
                                   XmlAttribute**  rcAttr
                                   /** A pointer to the replaced {\bf Attr}, if
                                   it exists. */
                                  );

    /** Returns a {\bf NodeList} of all {\it descendant} {\bf Elements} with a
     *  given tag name, in the order in which they are encountered in the
     *  pre-order traversal of the {\bf Element} tree.
     *
     *  @return [NodeList*] A {\bf NodeList} of matching {\bf Element}s or
     *                      {\tt NULL} on an error.
     */

    XmlNodeList*
    XmlElementGetElementsByTagNameNS(XmlElement* element,
                                       /** The {\bf Element} from which to start
                                       the search. */
                                       DOMString namespaceURI,
                                       /** The namespace URI of the {\bf
                                           Element}s to find. */
                                       DOMString localName
                                       /** The local name of the {\bf Element}s
                                           to find. */
                                      );

    /** Queries whether the {\bf Element} has an attribute with the given name
     *  or a default value.
     *
     *  @return [BOOL] {\tt TRUE} if the {\bf Element} has an attribute with
     *                 this name or has a default value for that attribute,
     *                 otherwise {\tt FALSE}.
     */

    BOOL
    XmlElementHasAttribute(XmlElement* element,
                             /** The {\bf Element} on which to check for an
                             attribute. */
                             DOMString name
                             /** The name of the attribute for which to check. */
                            );

    /** Queries whether the {\bf Element} has an attribute with the given
     *  local name and namespace URI or has a default value for that attribute.
     *
     *  @return [BOOL] {\tt TRUE} if the {\bf Element} has an attribute with
     *                 the given namespace and local name or has a default
     *                 value for that attribute, otherwise {\tt FALSE}.
     */

    BOOL
    XmlElementHasAttributeNS(XmlElement* element,
                               /** The {\bf Element} on which to check for the
                               attribute. */
                               DOMString namespaceURI,
                               /** The namespace URI of the attribute. */
                               DOMString localName
                               /** The local name of the attribute. */
                              );

    /** Frees the given {\bf Element} and any subtree of the {\bf Element}.
     *
     *  @return [void] This function does not return a value.
     */

    void
    XmlElementFree(XmlElement* element
                     /** The {\bf Element} to free. */
                    );

//@}

    /*================================================================
    *
    *   NamedNodeMap interfaces
    *
    *
    *=================================================================*/

    /**@name Interface {\it NamedNodeMap}
     * A {\bf NamedNodeMap} object represents a list of objects that can be
     * accessed by name.  A {\bf NamedNodeMap} maintains the objects in
     * no particular order.  The {\bf Node} interface uses a {\bf NamedNodeMap}
     * to maintain the attributes of a node.
     */
//@{

    /** Returns the number of items contained in this {\bf NamedNodeMap}.
     *
     *  @return [unsigned long] The number of nodes in this map.
     */

    unsigned long
    XmlNamedNodeMapGetLength(XmlNamedNodeMap *nnMap
                               /** The {\bf NamedNodeMap} from which to retrieve
                               the size. */
                              );

    /** Retrieves a {\bf Node} from the {\bf NamedNodeMap} by name.
     *
     *  @return [Node*] A {\bf Node} or {\tt NULL} if there is an error.
     */

    XmlNode*
    XmlNamedNodeMapGetNamedItem(XmlNamedNodeMap *nnMap,
                                  /** The {\bf NamedNodeMap} to search. */
                                  DOMString name
                                  /** The name of the {\bf Node} to find. */
                                 );

    /** Adds a new {\bf Node} to the {\bf NamedNodeMap} using the {\bf Node}
     *  name attribute.
     *
     *  @return [Node*] The old {\bf Node} if the new {\bf Node} replaces it or
     *                  {\tt NULL} if the {\bf Node} was not in the
     *                  {\bf NamedNodeMap} before.
     */

    XmlNode*
    XmlNamedNodeMapSetNamedItem(XmlNamedNodeMap *nnMap,
                                  /** The {\bf NamedNodeMap} in which to add the
                                  new {\bf Node}. */
                                  XmlNode *  arg
                                  /** The new {\bf Node} to add to the {\bf
                                  NamedNodeMap}. */
                                 );

    /** Removes a {\bf Node} from a {\bf NamedNodeMap} specified by name.
     *
     *  @return [Node*] A pointer to the {\bf Node}, if found, or {\tt NULL} if
     *                  it wasn't.
     */

    XmlNode*
    XmlNamedNodeMapRemoveNamedItem(XmlNamedNodeMap *nnMap,
                                     /** The {\bf NamedNodeMap} from which to
                                     remove the item. */
                                     DOMString name
                                     /** The name of the item to remove. */
                                    );

    /** Retrieves a {\bf Node} from a {\bf NamedNodeMap} specified by a
     *  numerical index.
     *
     *  @return [Node*] A pointer to the {\bf Node}, if found, or {\tt NULL} if
     *                  it wasn't.
     */

    XmlNode*
    XmlNamedNodeMapItem(XmlNamedNodeMap *nnMap,
                          /** The {\bf NamedNodeMap} from which to remove the
                          {\bf Node}. */
                          unsigned long index
                          /** The index into the map to remove. */
                         );

// introduced in DOM level 2

    /** Retrieves a {\bf Node} from a {\bf NamedNodeMap} specified by
     *  namespace URI and local name.
     *
     *  @return [Node*] A pointer to the {\bf Node}, if found, or {\tt NULL} if
     *                  it wasn't
     */

    XmlNode*
    XmlNamedNodeMapGetNamedItemNS(XmlNamedNodeMap *nnMap,
                                    /** The {\bf NamedNodeMap} from which to
                                    remove the {\bf Node}. */
                                    DOMString *namespaceURI,
                                    /** The namespace URI of the {\bf Node} to
                                                        remove. */
                                    DOMString localName
                                    /** The local name of the {\bf Node} to
                                        remove. */
                                   );

    /** Adds a new {\bf Node} to the {\bf NamedNodeMap} using the {\bf Node}
     *  local name and namespace URI attributes.
     *
     *  @return [Node*] The old {\bf Node} if the new {\bf Node} replaces it or
     *                  {\tt NULL} if the {\bf Node} was not in the
     *                  {\bf NamedNodeMap} before.
     */

    XmlNode*
    TrixmlNamedNodeMapSetNamedItemNS(XmlNamedNodeMap *nnMap,
                                     /** The {\bf NamedNodeMap} in which to add
                                     the {\bf Node}. */
                                     XmlNode *  arg
                                     /** The {\bf Node} to add to the map. */
                                    );

    /** Removes a {\bf Node} from a {\bf NamedNodeMap} specified by
     *  namespace URI and local name.
     *
     *  @return [Node*] A pointer to the {\bf Node}, if found, or {\tt NULL} if
     *          it wasn't.
     */

    XmlNode*
    XmlNamedNodeMapRemoveNamedItemNS(XmlNamedNodeMap *nnMap,
                                       /** The {\bf NamedNodeMap} from which to
                                       remove the {\bf Node}. */
                                       DOMString namespaceURI,
                                       /** The namespace URI of the {\bf Node}
                                           to remove. */
                                       DOMString localName
                                       /** The local name of the {\bf Node} to
                                           remove. */
                                      );

    /** Frees a {\bf NamedNodeMap}.  The {\bf Node}s inside the map are not
     *  freed, just the {\bf NamedNodeMap} object.
     *
     *  @return [void] This function does not return a value.
     */

    void
    XmlNamedNodeMapFree(XmlNamedNodeMap *nnMap
                          /** The {\bf NamedNodeMap to free}. */
                         );

//@}

    /*================================================================
    *
    *   NodeList interfaces
    *
    *
    *=================================================================*/

    /**@name Interface {\it NodeList}
     * The {\bf NodeList} interface abstracts an ordered collection of
     * nodes.  Note that changes to the underlying nodes will change
     * the nodes contained in a {\bf NodeList}.  The DOM2-Core refers to
     * this as being {\it live}.
     */
//@{

    /** Retrieves a {\bf Node} from a {\bf NodeList} specified by a
     *  numerical index.
     *
     *  @return [Node*] A pointer to a {\bf Node} or {\tt NULL} if there was an
     *                  error.
     */

    XmlNode*
    XmlNodeListItem(XmlNodeList *nList,
                      /** The {\bf NodeList} from which to retrieve the {\bf
                          Node}. */
                      unsigned long index
                      /** The index into the {\bf NodeList} to retrieve. */
                     );

    /** Returns the number of {\bf Nodes} in a {\bf NodeList}.
     *
     *  @return [unsigned long] The number of {\bf Nodes} in the {\bf NodeList}.
     */

    unsigned long
    XmlNodeListLength(XmlNodeList *nList
                        /** The {\bf NodeList} for which to retrieve the
                            number of {\bf Nodes}. */
                       );

    /** Frees a {\bf NodeList} object.  Since the underlying {\bf Nodes} are
     *  references, they are not freed using this operating.  This only
     *  frees the {\bf NodeList} object.
     *
     *  @return [void] This function does not return a value.
     */

    void
    XmlNodeListFree(XmlNodeList *nList
                      /** The {\bf NodeList} to free.  */
                     );

//@} Interface NodeList
//@} DOM Interfaces

    /**@name TRINGLE XML API
     * The TRINGLE XML API contains utility functions that are not part of the standard
     * DOM interfaces.  They include functions to create a DOM structure from a
     * file or buffer, create an XML file from a DOM structure, and manipulate
     * DOMString objects.
     */
//@{

    /*================================================================
    *
    *   Xml interfaces
    *
    *
    *=================================================================*/

#define     XmlPrintDocument(doc)  XmlPrintNode((XmlNode *)doc)

#define XmlDocumenttoString(doc)	XmlNodeToString((XmlNode *)doc)

    /** Renders a {\bf Node} and all sub-elements into an XML text
     *  representation.  The caller is required to free the {\bf DOMString}
     *  returned from this function using {\bf XmlFreeDOMString} when it
     *  is no longer required.
     *
     *  Note that this function can be used for any {\bf Node}-derived
     *  interface.  A similar {\bf XmlPrintDocument} function is defined
     *  to avoid casting when printing whole documents. This function
     *  introduces lots of white space to print the {\bf DOMString} in readable
     *  format.
     *
     *  @return [DOMString] A {\bf DOMString} with the XML text representation
     *                      of the DOM tree or {\tt NULL} on an error.
     */

    DOMString
    XmlPrintNode(XmlNode *  doc
                   /** The root of the {\bf Node} tree to render to XML text. */
                  );

    /** Renders a {\bf Node} and all sub-elements into an XML text
     *  representation.  The caller is required to free the {\bf DOMString}
     *  returned from this function using {\bf XmlFreeDOMString} when it
     *  is no longer required.
     *
     *  Note that this function can be used for any {\bf Node}-derived
     *  interface.  A similar {\bf XmlPrintDocument} function is defined
     *  to avoid casting when printing whole documents.
     *
     *  @return [DOMString] A {\bf DOMString} with the XML text representation
     *                      of the DOM tree or {\tt NULL} on an error.
     */

    DOMString
    XmlNodeToString(XmlNode *  doc
                      /** The root of the {\bf Node} tree to render to XML text. */
                     );

    /** Parses an XML text buffer converting it into an TRINGLE XML DOM representation.
     *
     *  @return [Document*] A {\bf Document} if the buffer correctly parses or
     *                      {\tt NULL} on an error.
     */
    XmlDocument*
    XmlParseBuffer(char *buffer
                     /** The buffer that contains the XML text to convert to a
                         {\bf Document}. */
                    );


    /** Parses an XML text buffer converting it into an TRINGLE XML DOM representation.
     *
     *  The {\bf XmlParseBufferEx} API differs from the {\bf XmlParseBuffer}
     *  API in that it returns an error code representing the actual failure
     *  rather than just {\tt NULL}.
     *
     *  @return [int] An integer representing one of the following:
     *    \begin{itemize}
     *      \item {\tt XML_OK}: The operation completed successfully.
     *      \item {\tt XML_INVALID_PARAMETER}: The {\bf buffer} is not a valid
     *            pointer.
     *      \item {\tt XML_INSUFFICIENT_MEMORY}: Not enough free memory exists
     *            to complete this operation.
     *    \end{itemize}
     */

    int
    XmlParseBufferEx(char *buffer,
                       /** The buffer that contains the XML text to convert to a
                           {\bf Document}. */
                       XmlDocument** doc
                       /** A point to store the {\bf Document} if file correctly
                           parses or {\bf NULL} on an error. */
                      );

    /** Parses an XML text file converting it into an TRINGLE XML DOM representation.
     *
     *  @return [Document*] A {\bf Document} if the file correctly parses or
     *                      {\tt NULL} on an error.
     */

    XmlDocument*
    XmlLoadDocument(char* xmlFile
                      /** The filename of the XML text to convert to a {\bf
                          Document}. */
                     );

    /** Parses an XML text file converting it into an TRINGLE XML DOM representation.
     *
     *  The {\bf XmlLoadDocumentEx} API differs from the {\bf XmlLoadDocument}
     *  API in that it returns a an error code representing the actual failure
     *  rather than just {\tt NULL}.
     *
     *  @return [int] An integer representing one of the following:
     *    \begin{itemize}
     *      \item {\tt XML_OK}: The operation completed successfully.
     *      \item {\tt XML_INVALID_PARAMETER}: The {\bf xmlFile} is not a valid
     *            pointer.
     *      \item {\tt XML_INSUFFICIENT_MEMORY}: Not enough free memory exists
     *            to complete this operation.
     *    \end{itemize}
     */

    int
    XmlLoadDocumentEx(char* xmlFile,
                        /** The filename of the XML text to convert to a {\bf
                            Document}. */
                        XmlDocument** doc
                        /** A pointer to the {\bf Document} if file correctly
                            parses or {\bf NULL} on an error. */
                       );

    /** Clones an existing {\bf DOMString}.
     *
     *  @return [DOMString] A new {\bf DOMString} that is a duplicate of the
     *                      original or {\tt NULL} if the operation could not
     *                      be completed.
     */

    DOMString
    XmlCloneDOMString(const DOMString src
                        /** The source {\bf DOMString} to clone. */
                       );

    /** Frees a {\bf DOMString}.
     *
     *  @return [void] This function does not return a value.
     */

    void
    XmlFreeDOMString(DOMString buf
                       /** The {\bf DOMString} to free. */
                      );

#ifdef __cplusplus
}
#endif

//@} TRINGLE XML API

#endif  // _TRINGLE_XML_H_
